<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>BonoboItemHandler</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Libbonobo Reference Manual">
<link rel="up" href="monikers.html" title="Monikers">
<link rel="prev" href="libbonobo-bonobo-moniker-extender.html" title="BonoboMonikerExtender">
<link rel="next" href="libbonobo-bonobo-item-container.html" title="BonoboItemContainer">
<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="libbonobo-bonobo-moniker-extender.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="monikers.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Libbonobo Reference Manual</th>
<td><a accesskey="n" href="libbonobo-bonobo-item-container.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#libbonobo-bonobo-item-handler.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#libbonobo-bonobo-item-handler.description" class="shortcut">Description</a>
                   | 
                  <a href="#libbonobo-bonobo-item-handler.object-hierarchy" class="shortcut">Object Hierarchy</a>
</td></tr>
</table>
<div class="refentry">
<a name="libbonobo-bonobo-item-handler"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="libbonobo-bonobo-item-handler.top_of_page"></a>BonoboItemHandler</span></h2>
<p>BonoboItemHandler — Simple Moniker Arguments</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="libbonobo-bonobo-item-handler.synopsis"></a><h2>Synopsis</h2>
<a name="BonoboItemHandler"></a><pre class="synopsis">                    <a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler-struct" title="BonoboItemHandler">BonoboItemHandler</a>;
                    <a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandlerClass" title="BonoboItemHandlerClass">BonoboItemHandlerClass</a>;
<a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-handler-new" title="bonobo_item_handler_new ()">bonobo_item_handler_new</a>             (<em class="parameter"><code><span class="type">BonoboItemHandlerEnumObjectsFn</span> enum_objects</code></em>,
                                                         <em class="parameter"><code><span class="type">BonoboItemHandlerGetObjectFn</span> get_object</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
<a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-handler-new-closure" title="bonobo_item_handler_new_closure ()">bonobo_item_handler_new_closure</a>     (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *enum_objects</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *get_object</code></em>);
<a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-handler-construct" title="bonobo_item_handler_construct ()">bonobo_item_handler_construct</a>       (<em class="parameter"><code><a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="type">BonoboItemHandler</span></a> *handler</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *enum_objects</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *get_object</code></em>);
                    <a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemOption" title="BonoboItemOption">BonoboItemOption</a>;
<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> *            <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-option-parse" title="bonobo_item_option_parse ()">bonobo_item_option_parse</a>            (<em class="parameter"><code>const <span class="type">char</span> *option_string</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-options-free" title="bonobo_item_options_free ()">bonobo_item_options_free</a>            (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *options</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="libbonobo-bonobo-item-handler.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="synopsis">
  <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
   +----<a class="link" href="libbonobo-bonobo-object.html#BonoboObject">BonoboObject</a>
         +----BonoboItemHandler
</pre>
</div>
<div class="refsect1">
<a name="libbonobo-bonobo-item-handler.description"></a><h2>Description</h2>
<p>
    Sometimes you want to pass "arguments" to a component.
    Consider the component with the following OAFIID:
</p>
<p><code class="literal">OAFIID:GNOME_FileSelector</code></p>
<p>
    You might want to be able to set configuration options from
    its moniker name, without having to ever use the property bag
    API. For example:</p>
<p><code class="literal">
    OAFIID:GNOME_FileSelector!AcceptMimeTypes=image/*</code></p>
<div class="refsect2">
<a name="id3167965"></a><h3>Implementing it</h3>
<p>
	Create a BonoboItemHandler.  This component will
	let you do argument parsing of any kind.</p>
<p>
	You have to provide two functions: <code class="function">enumObjects</code>
	(this can be empty) and <code class="function">getObject</code>.</p>
<p>The getObject function will be called when the moniker
	mechanism is trying to resolve a set of arguments to your
	function.</p>
<p>Like this:</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="normal">Bonobo_Unknown</span>
<span class="function">getObject</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">BonoboItemHandler</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">h</span><span class="symbol">,</span><span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">item_name</span><span class="symbol">,</span>
<span class="normal">           </span><span class="usertype">gboolean</span><span class="normal"> only_if_exists</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">,</span>
<span class="normal">           </span><span class="usertype">CORBA_Environment</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">ev</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">        </span><span class="usertype">MyData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">m </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
<span class="normal">        </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function">strcmp</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">item_name</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"friendly"</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">==</span><span class="normal"> </span><span class="number">0</span><span class="symbol">)</span><span class="cbracket">{</span>
<span class="normal">                m</span><span class="symbol">-&gt;</span><span class="normal">friendly </span><span class="symbol">=</span><span class="normal"> true</span><span class="symbol">;</span>
<span class="normal">        </span><span class="cbracket">}</span>
<span class="normal">        </span><span class="comment">/* we just return ourselves */</span>
<span class="normal">        </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="libbonobo-bonobo-object.html#bonobo-object-dup-ref">bonobo_object_dup_ref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="libbonobo-bonobo-object.html#bonobo-object-corba-objref">bonobo_object_corba_objref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">h</span><span class="symbol">),</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
	So basically during the `getObject' operation you will be
	given a chance to process the `item_name' string which is
	basically like a command line argument (for the sake of
	explaining this) and based on this information you can
	customize your component.
    </p>
</div>
<hr>
<div class="refsect2">
<a name="id3168026"></a><h3>Sample functions</h3>
<p>
	Sometimes you will want to specify a bunch of options to
	configure your component, like this:
    </p>
<p><code class="literal">OAFIID:MyComponent!visible=true;image=blah.png</code></p>
<p>
	So we are separating the various options with semi-colons
	here.  To simplify your code, we have provided a couple of
	functions that given the following string:</p>
<p><code class="literal">visible=true;image=blah.png</code></p>
<p>Will return a GList split with BonoboItemOptions:</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GSList</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">l</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">x</span><span class="symbol">;</span>
<span class="normal">x </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="libbonobo-bonobo-item-handler.html#bonobo-item-option-parse">bonobo_item_option_parse</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"visible=true;image=blah.png"</span><span class="symbol">);</span>
<span class="keyword">for</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">l </span><span class="symbol">=</span><span class="normal"> x</span><span class="symbol">;</span><span class="normal"> l </span><span class="symbol">!=</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span><span class="normal"> l</span><span class="symbol">++)</span><span class="cbracket">{</span>
<span class="normal">    </span><span class="usertype">BonoboItemOption</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">io </span><span class="symbol">=</span><span class="normal"> l</span><span class="symbol">-&gt;</span><span class="normal">data</span><span class="symbol">;</span>
<span class="normal">    </span><span class="function">printf</span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Key=%s, Value=%s</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> io</span><span class="symbol">-&gt;</span><span class="normal">key</span><span class="symbol">,</span><span class="normal"> io</span><span class="symbol">-&gt;</span><span class="normal">value</span><span class="symbol">);</span>
<span class="cbracket">}</span>
<span class="function">bonobo_item_option_free</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">x</span><span class="symbol">);</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

</div>
</div>
<div class="refsect1">
<a name="libbonobo-bonobo-item-handler.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="BonoboItemHandler-struct"></a><h3>BonoboItemHandler</h3>
<pre class="programlisting">typedef struct _BonoboItemHandler BonoboItemHandler;</pre>
<p>
Bonobo::ItemHandler implementation
</p>
</div>
<hr>
<div class="refsect2">
<a name="BonoboItemHandlerClass"></a><h3>BonoboItemHandlerClass</h3>
<pre class="programlisting">typedef struct {
	BonoboObjectClass parent_class;

	POA_Bonobo_ItemContainer__epv epv;
} BonoboItemHandlerClass;
</pre>
<p>
BonoboItemHandler class
</p>
</div>
<hr>
<div class="refsect2">
<a name="bonobo-item-handler-new"></a><h3>bonobo_item_handler_new ()</h3>
<pre class="programlisting"><a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * bonobo_item_handler_new             (<em class="parameter"><code><span class="type">BonoboItemHandlerEnumObjectsFn</span> enum_objects</code></em>,
                                                         <em class="parameter"><code><span class="type">BonoboItemHandlerGetObjectFn</span> get_object</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
<p>
Creates a new BonoboItemHandler object.  These are used to hold
client sites.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>enum_objects</code></em> :</span></p></td>
<td>callback invoked for Bonobo::ItemContainer::enum_objects
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>get_object</code></em> :</span></p></td>
<td>callback invoked for Bonobo::ItemContainer::get_objects
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>extra data passed on the callbacks
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The newly created BonoboItemHandler object
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="bonobo-item-handler-new-closure"></a><h3>bonobo_item_handler_new_closure ()</h3>
<pre class="programlisting"><a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * bonobo_item_handler_new_closure     (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *enum_objects</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *get_object</code></em>);</pre>
<p>
Creates a new BonoboItemHandler object.  These are used to hold
client sites.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>enum_objects</code></em> :</span></p></td>
<td>closure invoked for Bonobo::ItemContainer::enum_objects
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>get_object</code></em> :</span></p></td>
<td>closure invoked for Bonobo::ItemContainer::get_objects
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The newly created BonoboItemHandler object
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="bonobo-item-handler-construct"></a><h3>bonobo_item_handler_construct ()</h3>
<pre class="programlisting"><a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="returnvalue">BonoboItemHandler</span></a> * bonobo_item_handler_construct       (<em class="parameter"><code><a class="link" href="libbonobo-bonobo-item-handler.html#BonoboItemHandler"><span class="type">BonoboItemHandler</span></a> *handler</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *enum_objects</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GClosure"><span class="type">GClosure</span></a> *get_object</code></em>);</pre>
<p>
Constructs the <em class="parameter"><code>container</code></em> BonoboObject using the provided closures
for the actual implementation.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handler</code></em> :</span></p></td>
<td>The handler object to construct
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>enum_objects</code></em> :</span></p></td>
<td>The closure implementing enumObjects
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>get_object</code></em> :</span></p></td>
<td>The closure implementing getObject
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The constructed BonoboItemContainer object.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="BonoboItemOption"></a><h3>BonoboItemOption</h3>
<pre class="programlisting">typedef struct {
	char *key;
	char *value;
} BonoboItemOption;
</pre>
<p>
A key-value pair.
</p>
</div>
<hr>
<div class="refsect2">
<a name="bonobo-item-option-parse"></a><h3>bonobo_item_option_parse ()</h3>
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> *            bonobo_item_option_parse            (<em class="parameter"><code>const <span class="type">char</span> *option_string</code></em>);</pre>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>option_string</code></em> :</span></p></td>
<td>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="bonobo-item-options-free"></a><h3>bonobo_item_options_free ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                bonobo_item_options_free            (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *options</code></em>);</pre>
<p>
Use this to release a list returned by <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-option-parse" title="bonobo_item_option_parse ()"><code class="function">bonobo_item_option_parse()</code></a>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>options</code></em> :</span></p></td>
<td>a GSList of BonoboItemOption structures that was returned by <a class="link" href="libbonobo-bonobo-item-handler.html#bonobo-item-option-parse" title="bonobo_item_option_parse ()"><code class="function">bonobo_item_option_parse()</code></a>
</td>
</tr></tbody>
</table></div>
</div>
</div>
<div class="refsect1">
<a name="libbonobo-bonobo-item-handler.see-also"></a><h2>See Also</h2>
<p>
   A simplistic implementation exists in <a class="link" href="libbonobo-bonobo-item-container.html#BonoboItemContainer"><span class="type">BonoboItemContainer</span></a>.
</p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.15.1</div>
</body>
</html>